base
base is the foundation for creating modular, unit testable and highly pluggable node.js applications, starting with a handful of common methods, like set
, get
, del
and use
.
Install
Install with npm:
$ npm install --save base
What is Base?
Base is a framework for rapidly creating high quality node.js applications, using plugins like building blocks.
Guiding principles
The core team follows these principles to help guide API decisions:
- Compact API surface: The smaller the API surface, the easier the library will be to learn and use.
- Easy to extend: Implementors can use any npm package, and write plugins in pure JavaScript. If you're building complex apps, Base simplifies inheritance.
- Easy to test: No special setup should be required to unit test
Base
or base plugins
Minimal API surface
The API was designed to provide only the minimum necessary functionality for creating a useful application, with or without plugins.
Base core
Base itself ships with only a handful of useful methods, such as:
.set
: for setting values on the instance.get
: for getting values from the instance.has
: to check if a property exists on the instance.define
: for setting non-enumerable values on the instance.use
: for adding plugins
Be generic
When deciding on method to add or remove, we try to answer these questions:
- Will all or most Base applications need this method?
- Will this method encourage practices or enforce conventions that are beneficial to implementors?
- Can or should this be done in a plugin instead?
Composability
Plugin system
It couldn't be easier to extend Base with any features or custom functionality you can think of.
Base plugins are just functions that take an instance of Base
:
var base = new Base();
function plugin(base) {
}
base.use(plugin);
Inheritance
Easily inherit Base using .extend
:
var Base = require('base');
function MyApp() {
Base.call(this);
}
Base.extend(MyApp);
var app = new MyApp();
app.set('a', 'b');
app.get('a');
Inherit or instantiate with a namespace
By default, the .get
, .set
and .has
methods set and get values from the root of the base
instance. You can customize this using the .namespace
method exposed on the exported function. For example:
var Base = require('base');
var base = Base.namespace('cache');
var app = base();
app.set('foo', 'bar');
console.log(app.cache.foo);
API
Usage
var Base = require('base');
var app = new Base();
app.set('foo', 'bar');
console.log(app.foo);
Create an instance of Base
with the given config
and options
.
Params
config
{Object}: If supplied, this object is passed to cache-base to merge onto the the instance upon instantiation.options
{Object}: If supplied, this object is used to initialize the base.options
object.
Example
var app = new Base({isApp: true}, {abc: true});
app.set('foo', 'bar');
console.log(app.baz);
console.log(app.foo);
console.log(app.get('isApp'));
console.log(app.get('foo'));
console.log(app.options.abc);
Set the given name
on app._name
and app.is*
properties. Used for doing lookups in plugins.
Params
name
{String}returns
{Boolean}
Example
app.is('foo');
console.log(app._name);
console.log(app.isFoo);
app.is('bar');
console.log(app.isFoo);
console.log(app.isBar);
console.log(app._name);
Returns true if a plugin has already been registered on an instance.
Plugin implementors are encouraged to use this first thing in a plugin
to prevent the plugin from being called more than once on the same
instance.
Params
name
{String}: The plugin name.register
{Boolean}: If the plugin if not already registered, to record it as being registered pass true
as the second argument.returns
{Boolean}: Returns true if a plugin is already registered.
Events
emits
: plugin
Emits the name of the plugin being registered. Useful for unit tests, to ensure plugins are only registered once.
Example
var base = new Base();
base.use(function(app) {
if (app.isRegistered('myPlugin')) return;
});
base.use(function(app) {
if (app.isRegistered('myPlugin', true)) return;
});
Define a plugin function to be called immediately upon init. Plugins are chainable and expose the following arguments to the plugin function:
Params
fn
{Function}: plugin function to callreturns
{Object}: Returns the item instance for chaining.
Example
var app = new Base()
.use(foo)
.use(bar)
.use(baz)
The .define
method is used for adding non-enumerable property on the instance. Dot-notation is not supported with define
.
Params
key
{String}: The name of the property to define.value
{any}returns
{Object}: Returns the instance for chaining.
Example
app.define('render', function(str, locals) {
return _.template(str)(locals);
});
Mix property key
onto the Base prototype. If base is inherited using Base.extend
this method will be overridden by a new mixin
method that will only add properties to the prototype of the inheriting application.
Params
key
{String}val
{Object|Array}returns
{Object}: Returns the base
instance for chaining.
Example
app.mixin('foo', function() {
});
Getter/setter used when creating nested instances of Base
, for storing a reference to the first ancestor instance. This works by setting an instance of Base
on the parent
property of a "child" instance. The base
property defaults to the current instance if no parent
property is defined.
Example
var first = new Base();
first.foo = 'bar';
var second = new Base();
second.parent = first;
var third = new Base();
third.parent = second;
console.log(first.base.foo);
console.log(second.base.foo);
console.log(third.base.foo);
Static method for adding global plugin functions that will be added to an instance when created.
Params
fn
{Function}: Plugin function to use on each instance.returns
{Object}: Returns the Base
constructor for chaining
Example
Base.use(function(app) {
app.foo = 'bar';
});
var app = new Base();
console.log(app.foo);
Static method for inheriting the prototype and static methods of the Base
class. This method greatly simplifies the process of creating inheritance-based applications. See static-extend for more details.
Params
Ctor
{Function}: constructor to extendmethods
{Object}: Optional prototype properties to mix in.returns
{Object}: Returns the Base
constructor for chaining
Example
var extend = cu.extend(Parent);
Parent.extend(Child);
Parent.extend(Child, {
foo: function() {},
bar: function() {}
});
Used for adding methods to the Base
prototype, and/or to the prototype of child instances. When a mixin function returns a function, the returned function is pushed onto the .mixins
array, making it available to be used on inheriting classes whenever Base.mixins()
is called (e.g. Base.mixins(Child)
).
Params
fn
{Function}: Function to callreturns
{Object}: Returns the Base
constructor for chaining
Example
Base.mixin(function(proto) {
proto.foo = function(msg) {
return 'foo ' + msg;
};
});
Static method for running global mixin functions against a child constructor. Mixins must be registered before calling this method.
Params
Child
{Function}: Constructor function of a child classreturns
{Object}: Returns the Base
constructor for chaining
Example
Base.extend(Child);
Base.mixins(Child);
Similar to util.inherit
, but copies all static properties, prototype properties, and getters/setters from Provider
to Receiver
. See class-utils for more details.
Params
Receiver
{Function}: Receiving (child) constructorProvider
{Function}: Providing (parent) constructorreturns
{Object}: Returns the Base
constructor for chaining
Example
Base.inherit(Foo, Bar);
In the wild
The following node.js applications were built with Base
:
Test coverage
Statements : 98.91% ( 91/92 )
Branches : 92.86% ( 26/28 )
Functions : 100% ( 17/17 )
Lines : 98.9% ( 90/91 )
History
v0.11.2
v0.11.0
Breaking changes
- Static
.use
and .run
methods are now non-enumerable
v0.9.0
Breaking changes
.is
no longer takes a function, a string must be passed- all remaining
.debug
code has been removed app._namespace
was removed (related to debug
).plugin
, .use
, and .define
no longer emit events.assertPlugin
was removed.lazy
was removed
About
Related projects
Contributing
Pull requests and stars are always welcome. For bugs and feature requests, please create an issue.
Contributors
Building docs
(This project's readme.md is generated by verb, please don't edit the readme directly. Any changes to the readme must be made in the .verb.md readme template.)
To generate the readme, run the following command:
$ npm install -g verbose/verb
Running tests
Running and reviewing unit tests is a great way to get familiarized with a library and its API. You can install dependencies and run tests with the following command:
$ npm install && npm test
Author
Jon Schlinkert
License
Copyright © 2017, Jon Schlinkert.
Released under the MIT License.
This file was generated by verb-generate-readme, v0.6.0, on September 07, 2017.